<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>StringReplace</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>StringReplace</h1>

<p>Replaces the specified substring with a new string.</p>

<pre class="Syntax">OutputVar := StrReplace(Haystack, SearchText [, ReplaceText, OutputVarCount, Limit := -1])  <em>; v1.1.21+</em>
StringReplace, OutputVar, InputVar, SearchText [, ReplaceText, ReplaceAll?]</pre>
<h3>Parameters</h3>
<dl>

  <dt>OutputVar</dt>
  <dd><p>The name of the variable in which to store the result of the replacement process.</p></dd>

  <dt>InputVar or Haystack</dt>
  <dd>
    <p>The name of the variable whose contents will be read from. Do not enclose the name in percent signs unless you want the <em>contents</em> of the variable to be used as the name.</p>
    <p>Since StrReplace() is a function, <em>Haystack</em> can be an expression.</p>
  </dd>

  <dt>SearchText</dt>
  <dd><p>The string to search for. Matching is not case sensitive unless <a href="StringCaseSense.htm">StringCaseSense</a> has been turned on.</p></dd>

  <dt>ReplaceText</dt>
  <dd><p><em>SearchText</em> will be replaced with this text. If omitted or blank, <em>SearchText</em> will be replaced with blank (empty). In other words, it will be omitted from <em>OutputVar</em>.</p></dd>
  
  <dt>OutputVarCount (<em>StrReplace</em>)</dt>
  <dd><p>The unquoted name of a variable in which to store the number of replacements that occurred (0 if none).</p></dd>
  
  <dt>Limit (<em>StrReplace</em>)</dt>
  <dd><p>If <em>Limit</em> is omitted, it defaults to -1, which replaces <strong>all</strong> occurrences of the pattern found in <em>Haystack</em>. Otherwise, specify the maximum number of replacements to allow. The part of <em>Haystack</em> to the right of the last replacement is left unchanged.</p></dd>

  <dt>ReplaceAll? (<em>StringReplace</em>)</dt>
  <dd><p>If omitted, only the first occurrence of <em>SearchText</em> will be replaced. But if this parameter is 1, A, or All, all occurrences will be replaced.</p>
    <p>Specify the word <strong>UseErrorLevel</strong> to store in ErrorLevel the number of occurrences replaced (0 if none). UseErrorLevel implies &quot;All&quot;.</p>
    </dd>

</dl>

<h3>ErrorLevel</h3>
<p><strong>StrReplace:</strong> ErrorLevel is not set.</p>
<p><strong>StringReplace:</strong> When the last parameter is <em>UseErrorLevel</em>, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is given the number occurrences replaced (0 if none). Otherwise, ErrorLevel is set to 1 if <em>SearchText</em> is not found within <em>InputVar</em>, or 0 if it is found.</p>
<h3>Remarks</h3>
<p>For this and all other commands, <em>OutputVar</em> is allowed to be the same variable as an <em>InputVar</em>.</p>
<p>The built-in variables <a href="../Variables.htm">%A_Space%</a> and <a href="../Variables.htm">%A_Tab%</a> contain a single space and a single tab character, respectively. They are useful when searching for spaces and tabs alone or at the beginning or end of <em>SearchText</em>.</p>
<p>In v1.0.45, the AllSlow option became obsolete due to improvements to performance and memory utilization. Although it may still be specified, it has no effect.</p>
<h3>Related</h3>
<p><a href="RegExReplace.htm">RegExReplace()</a>, <a href="IfInString.htm">IfInString</a>, <a href="StringCaseSense.htm">StringCaseSense</a>, <a href="StringLeft.htm">StringLeft</a>, <a href="StringLeft.htm">StringRight</a>, <a href="StringMid.htm">StringMid</a>, <a href="StringTrimLeft.htm">StringTrimLeft</a>, <a href="StringTrimLeft.htm">StringTrimRight</a>, <a href="StringLen.htm">StringLen</a>, <a href="StringLower.htm">StringLower</a>, <a href="StringLower.htm">StringUpper</a>, <a href="StringGetPos.htm">StringGetPos</a>,  <a href="IfIs.htm">if var is type</a></p>
<h3>Examples</h3>
<pre class="NoIndent"><em>; Remove all CR+LF's from the clipboard contents:</em>
StringReplace, clipboard, clipboard, `r`n, , All

<em>; Replace all spaces with pluses:</em>
StringReplace, NewStr, OldStr, %A_SPACE%, +, All

<em>; Remove all blank lines from the text in a variable:</em>
Loop
{
    StringReplace, MyString, MyString, `r`n`r`n, `r`n, UseErrorLevel
    if ErrorLevel = 0  <em>; No more replacements needed.</em>
        break
}</pre>

</body>
</html>